<!DOCTYPE html>












  


<html class="theme-next mist use-motion" lang="zh-CN">
<head><meta name="generator" content="Hexo 3.8.0">
  <meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=2">
<meta name="theme-color" content="#222">


  <script>
  (function(i,s,o,g,r,a,m){i["DaoVoiceObject"]=r;i[r]=i[r]||function(){(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;a.charset="utf-8";m.parentNode.insertBefore(a,m)})(window,document,"script",('https:' == document.location.protocol ? 'https:' : 'http:') + "//widget.daovoice.io/widget/0f81ff2f.js","daovoice")
  daovoice('init', {
      app_id: "15fc8e87"
    });
  daovoice('update');
  </script>






  
  
    
    
  <script src="/lib/pace/pace.min.js?v=1.0.2"></script>
  <link href="/lib/pace/pace-theme-minimal.min.css?v=1.0.2" rel="stylesheet">







<meta http-equiv="Cache-Control" content="no-transform">
<meta http-equiv="Cache-Control" content="no-siteapp">






















<link href="/lib/font-awesome/css/font-awesome.min.css?v=4.6.2" rel="stylesheet" type="text/css">

<link href="/css/main.css?v=6.3.0" rel="stylesheet" type="text/css">


  <link rel="apple-touch-icon" sizes="180x180" href="/images/apple-touch-icon-next.png?v=6.3.0">


  <link rel="icon" type="image/png" sizes="32x32" href="/images/favicon-32x32-next.png?v=6.3.0">


  <link rel="icon" type="image/png" sizes="16x16" href="/images/favicon-16x16-next.png?v=6.3.0">


  <link rel="mask-icon" href="/images/logo.svg?v=6.3.0" color="#222">









<script type="text/javascript" id="hexo.configurations">
  var NexT = window.NexT || {};
  var CONFIG = {
    root: '/',
    scheme: 'Mist',
    version: '6.3.0',
    sidebar: {"position":"left","display":"post","offset":12,"b2t":true,"scrollpercent":true,"onmobile":false},
    fancybox: false,
    fastclick: false,
    lazyload: false,
    tabs: true,
    motion: {"enable":true,"async":false,"transition":{"post_block":"fadeIn","post_header":"slideDownIn","post_body":"slideDownIn","coll_header":"slideLeftIn","sidebar":"slideUpIn"}},
    algolia: {
      applicationID: '',
      apiKey: '',
      indexName: '',
      hits: {"per_page":10},
      labels: {"input_placeholder":"Search for Posts","hits_empty":"We didn't find any results for the search: ${query}","hits_stats":"${hits} results found in ${time} ms"}
    }
  };
</script>


  




  <meta name="description" content="使用Swagger来规范并自动化你的API文档">
<meta name="keywords" content="Swagger,api,文档">
<meta property="og:type" content="article">
<meta property="og:title" content="如何优雅的“编写”api接口文档">
<meta property="og:url" content="http://blog.wangxc.club/2017/05/03/如何优雅的“编写”api接口文档/index.html">
<meta property="og:site_name" content="冬与晨">
<meta property="og:description" content="使用Swagger来规范并自动化你的API文档">
<meta property="og:locale" content="zh-CN">
<meta property="og:image" content="http://upload-images.jianshu.io/upload_images/3167229-ec0d13bf3b0c9da5.png?imageMogr2/auto-orient/strip%7CimageView2/2/w/1240">
<meta property="og:updated_time" content="2018-06-29T13:58:50.283Z">
<meta name="twitter:card" content="summary">
<meta name="twitter:title" content="如何优雅的“编写”api接口文档">
<meta name="twitter:description" content="使用Swagger来规范并自动化你的API文档">
<meta name="twitter:image" content="http://upload-images.jianshu.io/upload_images/3167229-ec0d13bf3b0c9da5.png?imageMogr2/auto-orient/strip%7CimageView2/2/w/1240">






  <link rel="canonical" href="http://blog.wangxc.club/2017/05/03/如何优雅的“编写”api接口文档/">



<script type="text/javascript" id="page.configurations">
  CONFIG.page = {
    sidebar: "",
  };
</script>

  <title>如何优雅的“编写”api接口文档 | 冬与晨</title>
  




<script async src="https://www.googletagmanager.com/gtag/js?id=UA-102769182-1"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());

  gtag('config', 'UA-102769182-1');
</script>



  <script type="text/javascript">
    var _hmt = _hmt || [];
    (function() {
      var hm = document.createElement("script");
      hm.src = "https://hm.baidu.com/hm.js?809d5610fca8eaff344d9a698536110d";
      var s = document.getElementsByTagName("script")[0];
      s.parentNode.insertBefore(hm, s);
    })();
  </script>




  <noscript>
  <style type="text/css">
    .use-motion .motion-element,
    .use-motion .brand,
    .use-motion .menu-item,
    .sidebar-inner,
    .use-motion .post-block,
    .use-motion .pagination,
    .use-motion .comments,
    .use-motion .post-header,
    .use-motion .post-body,
    .use-motion .collection-title { opacity: initial; }

    .use-motion .logo,
    .use-motion .site-title,
    .use-motion .site-subtitle {
      opacity: initial;
      top: initial;
    }

    .use-motion {
      .logo-line-before i { left: initial; }
      .logo-line-after i { right: initial; }
    }
  </style>
</noscript>

</head>

<body itemscope itemtype="http://schema.org/WebPage" lang="zh-CN">

  
  
    
  

  <div class="container sidebar-position-left page-post-detail">
    <div class="headband">
    </div>
<a href="https://github.com/vector4wang"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub"></a>
    <header id="header" class="header" itemscope itemtype="http://schema.org/WPHeader">
      <div class="header-inner"><div class="site-brand-wrapper">
  <div class="site-meta ">
    

    <div class="custom-logo-site-title">
      <a href="/" class="brand" rel="start">
        <span class="logo-line-before"><i></i></span>
        <span class="site-title">冬与晨</span>
        <span class="logo-line-after"><i></i></span>
      </a>
    </div>
    
  </div>

  <div class="site-nav-toggle">
    <button aria-label="切换导航栏">
      <span class="btn-bar"></span>
      <span class="btn-bar"></span>
      <span class="btn-bar"></span>
    </button>
  </div>
</div>



<nav class="site-nav">
  
    <ul id="menu" class="menu">
      
        
        
        
          
          <li class="menu-item menu-item-home">
    <a href="/" rel="section">
      <i class="menu-item-icon fa fa-fw fa-home"></i> <br>首页</a>
  </li>
        
        
        
          
          <li class="menu-item menu-item-about">
    <a href="/about/" rel="section">
      <i class="menu-item-icon fa fa-fw fa-user"></i> <br>关于</a>
  </li>
        
        
        
          
          <li class="menu-item menu-item-tags">
    <a href="/tags/" rel="section">
      <i class="menu-item-icon fa fa-fw fa-tags"></i> <br>标签</a>
  </li>
        
        
        
          
          <li class="menu-item menu-item-categories">
    <a href="/categories/" rel="section">
      <i class="menu-item-icon fa fa-fw fa-th"></i> <br>分类</a>
  </li>
        
        
        
          
          <li class="menu-item menu-item-archives">
    <a href="/archives/" rel="section">
      <i class="menu-item-icon fa fa-fw fa-archive"></i> <br>归档</a>
  </li>
        
        
        
          
          <li class="menu-item menu-item-commonweal">
    <a href="/404/" rel="section">
      <i class="menu-item-icon fa fa-fw fa-heartbeat"></i> <br>公益 404</a>
  </li>

      
      
    </ul>
  

  
    

  

  
</nav>



  



</div>
    </header>

    


    <main id="main" class="main">
      <div class="main-inner">
        <div class="content-wrap">
          
          <div id="content" class="content">
            

  <div id="posts" class="posts-expand">
    

  

  
  
  

  

  <article class="post post-type-normal" itemscope itemtype="http://schema.org/Article">
  
  
  
  <div class="post-block">
    <link itemprop="mainEntityOfPage" href="http://blog.wangxc.club/2017/05/03/如何优雅的“编写”api接口文档/">

    <span hidden itemprop="author" itemscope itemtype="http://schema.org/Person">
      <meta itemprop="name" content="wangxc">
      <meta itemprop="description" content="革命尚未成功，同志还需努力~">
      <meta itemprop="image" content="/images/avatar.jpg">
    </span>

    <span hidden itemprop="publisher" itemscope itemtype="http://schema.org/Organization">
      <meta itemprop="name" content="冬与晨">
    </span>

    
      <header class="post-header">

        
        
          <h2 class="post-title" itemprop="name headline">如何优雅的“编写”api接口文档
              
            
          </h2>
        

        <div class="post-meta">
          <span class="post-time">

            
            
            

            
              <span class="post-meta-item-icon">
                <i class="fa fa-calendar-o"></i>
              </span>
              
                <span class="post-meta-item-text">发表于</span>
              

              
                
              

              <time title="创建时间：2017-05-03 23:51:34" itemprop="dateCreated datePublished" datetime="2017-05-03T23:51:34+08:00">2017-05-03</time>
            

            
              

              
                
                <span class="post-meta-divider">|</span>
                

                <span class="post-meta-item-icon">
                  <i class="fa fa-calendar-check-o"></i>
                </span>
                
                  <span class="post-meta-item-text">更新于</span>
                
                <time title="修改时间：2018-06-29 21:58:50" itemprop="dateModified" datetime="2018-06-29T21:58:50+08:00">2018-06-29</time>
              
            
          </span>

          
            <span class="post-category">
            
              <span class="post-meta-divider">|</span>
            
              <span class="post-meta-item-icon">
                <i class="fa fa-folder-o"></i>
              </span>
              
                <span class="post-meta-item-text">分类于</span>
              
              
                <span itemprop="about" itemscope itemtype="http://schema.org/Thing"><a href="/categories/技术/" itemprop="url" rel="index"><span itemprop="name">技术</span></a></span>

                
                
              
            </span>
          

          
            
              <span class="post-comments-count">
                <span class="post-meta-divider">|</span>
                <span class="post-meta-item-icon">
                  <i class="fa fa-comment-o"></i>
                </span>
                <a href="/2017/05/03/如何优雅的“编写”api接口文档/#comments" itemprop="discussionUrl">
                  <span class="post-meta-item-text">评论数：</span> <span class="post-comments-count valine-comment-count" data-xid="/2017/05/03/如何优雅的“编写”api接口文档/" itemprop="commentCount"></span>
                </a>
              </span>
            
          

          
          

          

          

          

        </div>
      </header>
    

    
    
    
    <div class="post-body" itemprop="articleBody">

      
      

      
        <p>使用Swagger来规范并自动化你的API文档</p>
<a id="more"></a>

<h3 id="前言"><a href="#前言" class="headerlink" title="前言"></a>前言</h3><p>　　今天我需要把之前写的接口整理成文档，老大给了意见<strong>用swagger</strong>搞，我像发现新大陆一样的兴奋，迫不及待得去“占有”它。<br>　　<code>Swagger</code>很容易上手，我花了十几分钟就搞定了。正好接着之前的<a href="/2017/04/24/如何优雅的格式化接口/">如何优雅的格式化接口</a>，这里再说一下SpringBoot整合Swagger的简单过程吧</p>
<h3 id="Swagger介绍"><a href="#Swagger介绍" class="headerlink" title="Swagger介绍"></a>Swagger介绍</h3><p>　　每每get新的技能想分享的时候，按照套路来讲，需要有一个版块将该技能的“前世今生”介绍个遍，但就我接触到完成配置不超过半小时，我觉得让我完完整整的介绍有点太虚了，所以，最好的介绍就是下面的官网<br><a href="http://swagger.io/" target="_blank" rel="noopener">http://swagger.io/</a><br><a href="http://swagger.io/irc/" target="_blank" rel="noopener">http://swagger.io/irc/</a> 这个是实时聊天室，刚刚和老外沟通了一番“how are you？fine thk you.and you?”<br><a href="https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel" target="_blank" rel="noopener">https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel</a> 这个是一些注解的api<br>Swagger有三个模块</p>
<ul>
<li>Swagger Editor</li>
<li>Swagger UI</li>
<li>Swagger Codegen</li>
</ul>
<p>　　我使用的是Swagger UI，我个人的理解就是“使用Swagger相关的注解并启动服务后，就可以在对应的页面查看API并<strong>测试</strong>”，先看一下最终的界面<br>　　<br><img src="http://upload-images.jianshu.io/upload_images/3167229-ec0d13bf3b0c9da5.png?imageMogr2/auto-orient/strip%7CimageView2/2/w/1240" alt="api.png"><br>接口描述、参数类型、返回示例在线调试都给你搞定了。你还在犹豫什么，赶快checkou代码，试一试吧</p>
<h3 id="整合"><a href="#整合" class="headerlink" title="整合"></a>整合</h3><p>　　我接着之前的代码的写(可以在我的<a href="https://github.com/vector4wang/springbootquick" target="_blank" rel="noopener">GitHub</a>上浏览，或者直接clone到本地再切换到<strong>api-norms</strong>分支)，这里要说一下，使用Springboot整合Swagger贼JB简单，相比较而言，SpringMVC就比较复杂了，这里暂且不谈（以后可能也不会谈了，自从我使用了Springboot之后，就已经开始抛弃SpringMVC了）</p>
<h4 id="maven依赖"><a href="#maven依赖" class="headerlink" title="maven依赖"></a>maven依赖</h4><p>老规矩上配置</p>
<figure class="highlight xml"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="name">dependency</span>&gt;</span></span><br><span class="line">    <span class="tag">&lt;<span class="name">groupId</span>&gt;</span>io.springfox<span class="tag">&lt;/<span class="name">groupId</span>&gt;</span></span><br><span class="line">    <span class="tag">&lt;<span class="name">artifactId</span>&gt;</span>springfox-swagger2<span class="tag">&lt;/<span class="name">artifactId</span>&gt;</span></span><br><span class="line">    <span class="tag">&lt;<span class="name">version</span>&gt;</span>$&#123;swagger.version&#125;<span class="tag">&lt;/<span class="name">version</span>&gt;</span></span><br><span class="line"><span class="tag">&lt;/<span class="name">dependency</span>&gt;</span></span><br><span class="line"><span class="tag">&lt;<span class="name">dependency</span>&gt;</span></span><br><span class="line">    <span class="tag">&lt;<span class="name">groupId</span>&gt;</span>io.springfox<span class="tag">&lt;/<span class="name">groupId</span>&gt;</span></span><br><span class="line">    <span class="tag">&lt;<span class="name">artifactId</span>&gt;</span>springfox-swagger-ui<span class="tag">&lt;/<span class="name">artifactId</span>&gt;</span></span><br><span class="line">    <span class="tag">&lt;<span class="name">version</span>&gt;</span>$&#123;swagger.version&#125;<span class="tag">&lt;/<span class="name">version</span>&gt;</span></span><br><span class="line"><span class="tag">&lt;/<span class="name">dependency</span>&gt;</span></span><br></pre></td></tr></table></figure>

<h4 id="添加Swagger注解"><a href="#添加Swagger注解" class="headerlink" title="添加Swagger注解"></a>添加<code>Swagger</code>注解</h4><p>　　在Application上直接添加<code>@EnableSwagger2</code>，注意版本，官网上的版本还没有更新到最新的，最新的在<a href="https://github.com/swagger-api/swagger-ui" target="_blank" rel="noopener">Github</a>上看,配置后的代码</p>
<figure class="highlight java"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">import</span> org.springframework.boot.SpringApplication;</span><br><span class="line"><span class="keyword">import</span> org.springframework.boot.autoconfigure.SpringBootApplication;</span><br><span class="line"><span class="keyword">import</span> springfox.documentation.swagger2.annotations.EnableSwagger2;</span><br><span class="line"></span><br><span class="line"><span class="comment">/**</span></span><br><span class="line"><span class="comment"> * Created by wangxc on 2017/3/9.</span></span><br><span class="line"><span class="comment"> */</span></span><br><span class="line"><span class="meta">@SpringBootApplication</span></span><br><span class="line"><span class="meta">@EnableSwagger</span>2</span><br><span class="line"><span class="keyword">public</span> <span class="class"><span class="keyword">class</span> <span class="title">Application</span> </span>&#123;</span><br><span class="line"></span><br><span class="line">    <span class="function"><span class="keyword">public</span> <span class="keyword">static</span> <span class="keyword">void</span> <span class="title">main</span><span class="params">(String[] args)</span> </span>&#123;</span><br><span class="line">        SpringApplication.run(Application.class, args);</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure>

<p>可以了，接下来就是描述接口的注解了！在Controller层，做如下配置</p>
<figure class="highlight java"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br><span class="line">37</span><br><span class="line">38</span><br><span class="line">39</span><br><span class="line">40</span><br><span class="line">41</span><br><span class="line">42</span><br><span class="line">43</span><br><span class="line">44</span><br><span class="line">45</span><br><span class="line">46</span><br><span class="line">47</span><br><span class="line">48</span><br><span class="line">49</span><br><span class="line">50</span><br><span class="line">51</span><br><span class="line">52</span><br><span class="line">53</span><br><span class="line">54</span><br><span class="line">55</span><br><span class="line">56</span><br><span class="line">57</span><br><span class="line">58</span><br><span class="line">59</span><br><span class="line">60</span><br><span class="line">61</span><br><span class="line">62</span><br><span class="line">63</span><br><span class="line">64</span><br><span class="line">65</span><br><span class="line">66</span><br><span class="line">67</span><br><span class="line">68</span><br><span class="line">69</span><br><span class="line">70</span><br><span class="line">71</span><br><span class="line">72</span><br><span class="line">73</span><br><span class="line">74</span><br><span class="line">75</span><br><span class="line">76</span><br><span class="line">77</span><br><span class="line">78</span><br><span class="line">79</span><br><span class="line">80</span><br><span class="line">81</span><br><span class="line">82</span><br><span class="line">83</span><br><span class="line">84</span><br><span class="line">85</span><br><span class="line">86</span><br><span class="line">87</span><br><span class="line">88</span><br><span class="line">89</span><br><span class="line">90</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">package</span> com.quick.api;</span><br><span class="line"></span><br><span class="line"></span><br><span class="line"><span class="keyword">import</span> com.quick.po.Address;</span><br><span class="line"><span class="keyword">import</span> com.quick.utils.BaseResp;</span><br><span class="line"><span class="keyword">import</span> com.quick.utils.ResultStatus;</span><br><span class="line"><span class="keyword">import</span> io.swagger.annotations.*;</span><br><span class="line"><span class="keyword">import</span> org.springframework.util.StringUtils;</span><br><span class="line"><span class="keyword">import</span> org.springframework.web.bind.annotation.RequestMapping;</span><br><span class="line"><span class="keyword">import</span> org.springframework.web.bind.annotation.RequestMethod;</span><br><span class="line"><span class="keyword">import</span> org.springframework.web.bind.annotation.RequestParam;</span><br><span class="line"><span class="keyword">import</span> org.springframework.web.bind.annotation.RestController;</span><br><span class="line"></span><br><span class="line"><span class="keyword">import</span> java.util.ArrayList;</span><br><span class="line"><span class="keyword">import</span> java.util.List;</span><br><span class="line"></span><br><span class="line"><span class="comment">/**</span></span><br><span class="line"><span class="comment"> * Created with IDEA</span></span><br><span class="line"><span class="comment"> * User: vector</span></span><br><span class="line"><span class="comment"> * Data: 2017/4/12</span></span><br><span class="line"><span class="comment"> * Time: 8:41</span></span><br><span class="line"><span class="comment"> * Description:</span></span><br><span class="line"><span class="comment"> */</span></span><br><span class="line"><span class="meta">@RestController</span></span><br><span class="line"><span class="meta">@RequestMapping</span>(<span class="string">"/api"</span>)</span><br><span class="line"><span class="meta">@Api</span>(<span class="string">"springboot整合swagger2"</span>) <span class="comment">// Swagger UI 对应api的标题描述</span></span><br><span class="line"><span class="keyword">public</span> <span class="class"><span class="keyword">class</span> <span class="title">WebController</span> </span>&#123;</span><br><span class="line"></span><br><span class="line">    <span class="meta">@ApiOperation</span>(<span class="string">"获取地址信息"</span>) <span class="comment">// 单个接口的描述</span></span><br><span class="line">    <span class="meta">@ApiImplicitParams</span>(&#123;</span><br><span class="line">            <span class="meta">@ApiImplicitParam</span>(paramType=<span class="string">"query"</span>,name=<span class="string">"province"</span>,dataType=<span class="string">"String"</span>,required=<span class="keyword">true</span>,value=<span class="string">"省"</span>,defaultValue=<span class="string">"广东省"</span>),<span class="comment">// 每个参数的类型，名称，数据类型，是否校验，描述，默认值(这些在界面上有展示)</span></span><br><span class="line">            <span class="meta">@ApiImplicitParam</span>(paramType=<span class="string">"query"</span>,name=<span class="string">"area"</span>,dataType=<span class="string">"String"</span>,required=<span class="keyword">true</span>,value=<span class="string">"地区"</span>,defaultValue=<span class="string">"南山区"</span>),</span><br><span class="line">            <span class="meta">@ApiImplicitParam</span>(paramType=<span class="string">"query"</span>,name=<span class="string">"street"</span>,dataType=<span class="string">"String"</span>,required=<span class="keyword">true</span>,value=<span class="string">"街道"</span>,defaultValue=<span class="string">"桃园路"</span>),</span><br><span class="line">            <span class="meta">@ApiImplicitParam</span>(paramType=<span class="string">"query"</span>,name=<span class="string">"num"</span>,dataType=<span class="string">"String"</span>,required=<span class="keyword">true</span>,value=<span class="string">"门牌号"</span>,defaultValue=<span class="string">"666"</span>)</span><br><span class="line">    &#125;)</span><br><span class="line">    <span class="meta">@ApiResponses</span>(&#123;</span><br><span class="line">            <span class="meta">@ApiResponse</span>(code=<span class="number">400</span>,message=<span class="string">"请求参数没填好"</span>), <span class="comment">// 响应对应编码的描述</span></span><br><span class="line">            <span class="meta">@ApiResponse</span>(code=<span class="number">404</span>,message=<span class="string">"请求路径没有或页面跳转路径不对"</span>)</span><br><span class="line">    &#125;)</span><br><span class="line">    <span class="meta">@RequestMapping</span>(value = <span class="string">"/address"</span>,method = RequestMethod.POST)</span><br><span class="line">    <span class="function"><span class="keyword">public</span> BaseResp&lt;Address&gt; <span class="title">getAddressInfo</span><span class="params">(@RequestParam(value = <span class="string">"province"</span>)</span>String province,</span></span><br><span class="line"><span class="function">                                   @<span class="title">RequestParam</span><span class="params">(value = <span class="string">"area"</span>)</span>String area,</span></span><br><span class="line"><span class="function">                                   @<span class="title">RequestParam</span><span class="params">(value = <span class="string">"street"</span>)</span>String street,</span></span><br><span class="line"><span class="function">                                   @<span class="title">RequestParam</span><span class="params">(value = <span class="string">"num"</span>)</span>String num)</span>&#123;</span><br><span class="line"></span><br><span class="line">        <span class="keyword">if</span>(StringUtils.isEmpty(province)||StringUtils.isEmpty(area)||StringUtils.isEmpty(street)||StringUtils.isEmpty(num))&#123;</span><br><span class="line">            <span class="keyword">return</span> <span class="keyword">new</span> BaseResp(ResultStatus.error_invalid_argument);</span><br><span class="line">        &#125;</span><br><span class="line">        Address address = <span class="keyword">new</span> Address();</span><br><span class="line">        address.setProvince(province);</span><br><span class="line">        address.setArea(area);</span><br><span class="line">        address.setStreet(street);</span><br><span class="line">        address.setNum(num);</span><br><span class="line">        <span class="keyword">return</span> <span class="keyword">new</span> BaseResp(ResultStatus.SUCCESS,address);</span><br><span class="line"></span><br><span class="line">    &#125;</span><br><span class="line"></span><br><span class="line">    <span class="meta">@ApiOperation</span>(<span class="string">"获取地址信息"</span>)</span><br><span class="line">    <span class="meta">@ApiImplicitParams</span>(&#123;</span><br><span class="line">            <span class="meta">@ApiImplicitParam</span>(paramType=<span class="string">"query"</span>,name=<span class="string">"province"</span>,dataType=<span class="string">"String"</span>,required=<span class="keyword">true</span>,value=<span class="string">"省"</span>,defaultValue=<span class="string">"广东省"</span>),</span><br><span class="line">            <span class="meta">@ApiImplicitParam</span>(paramType=<span class="string">"query"</span>,name=<span class="string">"area"</span>,dataType=<span class="string">"String"</span>,required=<span class="keyword">true</span>,value=<span class="string">"地区"</span>,defaultValue=<span class="string">"南山区"</span>),</span><br><span class="line">            <span class="meta">@ApiImplicitParam</span>(paramType=<span class="string">"query"</span>,name=<span class="string">"street"</span>,dataType=<span class="string">"String"</span>,required=<span class="keyword">true</span>,value=<span class="string">"街道"</span>,defaultValue=<span class="string">"桃园路"</span>),</span><br><span class="line">            <span class="meta">@ApiImplicitParam</span>(paramType=<span class="string">"query"</span>,name=<span class="string">"num"</span>,dataType=<span class="string">"String"</span>,required=<span class="keyword">true</span>,value=<span class="string">"门牌号"</span>,defaultValue=<span class="string">"666"</span>)</span><br><span class="line">    &#125;)</span><br><span class="line">    <span class="meta">@ApiResponses</span>(&#123;</span><br><span class="line">            <span class="meta">@ApiResponse</span>(code=<span class="number">400</span>,message=<span class="string">"请求参数没填好"</span>),</span><br><span class="line">            <span class="meta">@ApiResponse</span>(code=<span class="number">404</span>,message=<span class="string">"请求路径没有或页面跳转路径不对"</span>)</span><br><span class="line">    &#125;)</span><br><span class="line">    <span class="meta">@RequestMapping</span>(value = <span class="string">"/address/list"</span>,method = RequestMethod.POST)</span><br><span class="line">    <span class="keyword">public</span> BaseResp&lt;List&lt;Address&gt;&gt; getAddressList(<span class="meta">@RequestParam</span>(value = <span class="string">"province"</span>)String province,</span><br><span class="line">                                             <span class="meta">@RequestParam</span>(value = <span class="string">"area"</span>)String area,</span><br><span class="line">                                             <span class="meta">@RequestParam</span>(value = <span class="string">"street"</span>)String street,</span><br><span class="line">                                             <span class="meta">@RequestParam</span>(value = <span class="string">"num"</span>)String num)&#123;</span><br><span class="line"></span><br><span class="line">        <span class="keyword">if</span>(StringUtils.isEmpty(province)||StringUtils.isEmpty(area)||StringUtils.isEmpty(street)||StringUtils.isEmpty(num))&#123;</span><br><span class="line">            <span class="keyword">return</span> <span class="keyword">new</span> BaseResp(ResultStatus.error_invalid_argument);</span><br><span class="line">        &#125;</span><br><span class="line">        Address address = <span class="keyword">new</span> Address();</span><br><span class="line">        address.setProvince(province);</span><br><span class="line">        address.setArea(area);</span><br><span class="line">        address.setStreet(street);</span><br><span class="line">        address.setNum(num);</span><br><span class="line">        List&lt;Address&gt; lists = <span class="keyword">new</span> ArrayList&lt;&gt;();</span><br><span class="line">        lists.add(address);</span><br><span class="line">        lists.add(address);</span><br><span class="line">        lists.add(address);</span><br><span class="line">        <span class="keyword">return</span> <span class="keyword">new</span> BaseResp(ResultStatus.SUCCESS,lists);</span><br><span class="line"></span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure>

<p>我只是在原来的基础上添加了下面注解</p>
<table>
<thead>
<tr>
<th align="left">名称</th>
<th>解释</th>
</tr>
</thead>
<tbody><tr>
<td align="left">@Api()</td>
<td>将类标记为一种Swagger资源。</td>
</tr>
<tr>
<td align="left">@ApiOperation()</td>
<td>描述针对特定路径的操作或通常是 http 方法。</td>
</tr>
<tr>
<td align="left">@ApiImplicitParams</td>
<td>允许多个 ApiImplicitParam 对象列表的包装。</td>
</tr>
<tr>
<td align="left">@ApiImplicitParam</td>
<td>表示 api 操作中的单个参数。</td>
</tr>
<tr>
<td align="left">@ApiResponses</td>
<td>允许多个 ApiResponse 对象列表的包装。</td>
</tr>
<tr>
<td align="left">@ApiResponse</td>
<td>描述操作的可能响应。</td>
</tr>
</tbody></table>
<p>更多的<a href="https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel" target="_blank" rel="noopener">看这里</a></p>
<p>就这么简单，一个基本而又强大的API文档就整理好了！</p>
<h3 id="启动"><a href="#启动" class="headerlink" title="启动"></a>启动</h3><p>正常的启动SpringBoot,你会发现控制台输出了这些内容</p>
<figure class="highlight console"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">2017-05-03 21:42:52,975  INFO ClassOrApiAnnotationResourceGrouping:100 - Group for method getAddressList was springboot整合swagger2</span><br><span class="line">2017-05-03 21:42:52,986  INFO ClassOrApiAnnotationResourceGrouping:100 - Group for method getAddressList was springboot整合swagger2</span><br></pre></td></tr></table></figure>

<p>说明Swagger已经成功跑起来了，接下来打开浏览器，输入你链接<br><strong>yourdomain/swagger-ui.html</strong><br>我的是<strong><a href="http://localhost:8080/swagger-ui.html" target="_blank" rel="noopener">http://localhost:8080/swagger-ui.html</a></strong></p>
<p>相信你看了界面并四处点点之后，就会对上面注解的含义有了更进一步的了解~</p>
<h3 id="后记"><a href="#后记" class="headerlink" title="后记"></a>后记</h3><p>　　这里展示的只是Swagger最基本的功能，更多强大的功能如果后面有运用，我会持续更新的。<br>　　目前我在看api寻找SwaggerUI输入文件的测试，因为我有个接口需要上传文件，等我搞定，再来分享吧！！</p>

      
    </div>

    

    
    
    

    <div>
          
            
          
    </div>

    

    
      <div>
        <div style="padding: 10px 0; margin: 20px auto; width: 90%; text-align: center;">
  <div></div>
  <button id="rewardButton" disable="enable" onclick="var qr = document.getElementById('QR'); if (qr.style.display === 'none') {qr.style.display='block';} else {qr.style.display='none'}">
    <span>打赏</span>
  </button>
  <div id="QR" style="display: none;">

    
      <div id="wechat" style="display: inline-block">
        <img id="wechat_qr" src="https://i.loli.net/2017/12/29/5a4632028eaeb.jpg" alt="wangxc 微信支付">
        <p>微信支付</p>
      </div>
    

    
      <div id="alipay" style="display: inline-block">
        <img id="alipay_qr" src="https://i.loli.net/2017/12/29/5a46320234b1d.jpg" alt="wangxc 支付宝">
        <p>支付宝</p>
      </div>
    

    

  </div>
</div>

      </div>
    

    
<div>
  
    <div>
    
        <div style="text-align:center;color: #ccc;font-size:14px;">
              -------------本文结束<i class="fa fa-paw"></i>感谢您的阅读-------------
        </div>
    
</div>

  
</div>
    <footer class="post-footer">
      
        <div class="post-tags">
          
            <a href="/tags/Swagger/" rel="tag"><i class="fa fa-tag"></i> Swagger</a>
          
            <a href="/tags/api/" rel="tag"><i class="fa fa-tag"></i> api</a>
          
            <a href="/tags/文档/" rel="tag"><i class="fa fa-tag"></i> 文档</a>
          
        </div>
      

      
      
      

      
        <div class="post-nav">
          <div class="post-nav-next post-nav-item">
            
              <a href="/2017/04/24/采集领英个人信息/" rel="next" title="采集领英个人信息">
                <i class="fa fa-chevron-left"></i> 采集领英个人信息
              </a>
            
          </div>

          <span class="post-nav-divider"></span>

          <div class="post-nav-prev post-nav-item">
            
              <a href="/2017/05/04/如何优雅的“编写”api接口文档（续）/" rel="prev" title="如何优雅的“编写”api接口文档（续）">
                如何优雅的“编写”api接口文档（续） <i class="fa fa-chevron-right"></i>
              </a>
            
          </div>
        </div>
      

      
      
    </footer>
  </div>
  
  
  
  </article>



    <div class="post-spread">
      
    </div>
  </div>


          </div>
          

  
    <div class="comments" id="comments">
    </div>
  



        </div>
        
          
  
  <div class="sidebar-toggle">
    <div class="sidebar-toggle-line-wrap">
      <span class="sidebar-toggle-line sidebar-toggle-line-first"></span>
      <span class="sidebar-toggle-line sidebar-toggle-line-middle"></span>
      <span class="sidebar-toggle-line sidebar-toggle-line-last"></span>
    </div>
  </div>

  <aside id="sidebar" class="sidebar">
    
    <div class="sidebar-inner">

      

      
        <ul class="sidebar-nav motion-element">
          <li class="sidebar-nav-toc sidebar-nav-active" data-target="post-toc-wrap">
            文章目录
          </li>
          <li class="sidebar-nav-overview" data-target="site-overview-wrap">
            站点概览
          </li>
        </ul>
      

      <section class="site-overview-wrap sidebar-panel">
        <div class="site-overview">
          <div class="site-author motion-element" itemprop="author" itemscope itemtype="http://schema.org/Person">
            
              <img class="site-author-image" itemprop="image" src="/images/avatar.jpg" alt="wangxc">
            
              <p class="site-author-name" itemprop="name">wangxc</p>
              <p class="site-description motion-element" itemprop="description">革命尚未成功，同志还需努力~</p>
          </div>

          
            <nav class="site-state motion-element">
              
                <div class="site-state-item site-state-posts">
                
                  <a href="/archives/">
                
                    <span class="site-state-item-count">83</span>
                    <span class="site-state-item-name">日志</span>
                  </a>
                </div>
              

              
                
                
                <div class="site-state-item site-state-categories">
                  <a href="/categories/index.html">
                    
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                    <span class="site-state-item-count">6</span>
                    <span class="site-state-item-name">分类</span>
                  </a>
                </div>
              

              
                
                
                <div class="site-state-item site-state-tags">
                  <a href="/tags/index.html">
                    
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                      
                    
                    <span class="site-state-item-count">124</span>
                    <span class="site-state-item-name">标签</span>
                  </a>
                </div>
              
            </nav>
          

          

          
            <div class="links-of-author motion-element">
              
                <span class="links-of-author-item">
                  <a href="https://github.com/vector4wang" target="_blank" title="GitHub" rel="external nofollow"><i class="fa fa-fw fa-github"></i>GitHub</a>
                  
                </span>
              
                <span class="links-of-author-item">
                  <a href="mailto:vector4wang@qq.com" target="_blank" title="E-Mail" rel="external nofollow"><i class="fa fa-fw fa-envelope"></i>E-Mail</a>
                  
                </span>
              
                <span class="links-of-author-item">
                  <a href="https://www.jianshu.com/u/223a1314e818" target="_blank" title="简书" rel="external nofollow"><i class="fa fa-fw fa-book"></i>简书</a>
                  
                </span>
              
                <span class="links-of-author-item">
                  <a href="http://blog.csdn.net/qqhjqs?viewmode=contents" target="_blank" title="CSDN" rel="external nofollow"><i class="fa fa-fw fa-crosshairs"></i>CSDN</a>
                  
                </span>
              
                <span class="links-of-author-item">
                  <a href="https://twitter.com/BMHJQS" target="_blank" title="Twitter" rel="external nofollow"><i class="fa fa-fw fa-twitter"></i>Twitter</a>
                  
                </span>
              
                <span class="links-of-author-item">
                  <a href="https://www.facebook.com/" target="_blank" title="FB Page" rel="external nofollow"><i class="fa fa-fw fa-facebook-official"></i>FB Page</a>
                  
                </span>
              
            </div>
          

          
          

          
          

          
            
          
          

        </div>
      </section>

      
      <!--noindex-->
        <section class="post-toc-wrap motion-element sidebar-panel sidebar-panel-active">
          <div class="post-toc">

            
              
            

            
              <div class="post-toc-content"><ol class="nav"><li class="nav-item nav-level-3"><a class="nav-link" href="#前言"><span class="nav-number">1.</span> <span class="nav-text">前言</span></a></li><li class="nav-item nav-level-3"><a class="nav-link" href="#Swagger介绍"><span class="nav-number">2.</span> <span class="nav-text">Swagger介绍</span></a></li><li class="nav-item nav-level-3"><a class="nav-link" href="#整合"><span class="nav-number">3.</span> <span class="nav-text">整合</span></a><ol class="nav-child"><li class="nav-item nav-level-4"><a class="nav-link" href="#maven依赖"><span class="nav-number">3.1.</span> <span class="nav-text">maven依赖</span></a></li><li class="nav-item nav-level-4"><a class="nav-link" href="#添加Swagger注解"><span class="nav-number">3.2.</span> <span class="nav-text">添加Swagger注解</span></a></li></ol></li><li class="nav-item nav-level-3"><a class="nav-link" href="#启动"><span class="nav-number">4.</span> <span class="nav-text">启动</span></a></li><li class="nav-item nav-level-3"><a class="nav-link" href="#后记"><span class="nav-number">5.</span> <span class="nav-text">后记</span></a></li></ol></div>
            

          </div>
        </section>
      <!--/noindex-->
      

      
        <div class="back-to-top">
          <i class="fa fa-arrow-up"></i>
          
            <span id="scrollpercent"><span>0</span>%</span>
          
        </div>
      

    </div>
  </aside>


        
      </div>
    </main>

    <footer id="footer" class="footer">
      <div class="footer-inner">
        <script async src="https://dn-lbstatics.qbox.me/busuanzi/2.3/busuanzi.pure.mini.js"></script>
<div class="copyright">&copy; <span itemprop="copyrightYear">2020</span>
  <span class="with-love" id="animate">
    <i class="fa fa-user"></i>
  </span>
  <span class="author" itemprop="copyrightHolder">wangxc</span>

  

  
</div>


  


<div class="powered-by">
<i class="fa fa-user-md"></i><span id="busuanzi_container_site_pv">
  本站访客数:<span id="busuanzi_value_site_uv"></span>
</span>
</div>


  <div class="powered-by">由 <a class="theme-link" target="_blank" rel="external nofollow" href="https://hexo.io">Hexo</a> 强力驱动 v3.8.0</div>



  <span class="post-meta-divider">|</span>



  <div class="theme-info">主题 &mdash; <a class="theme-link" target="_blank" rel="external nofollow" href="https://theme-next.org">NexT.Mist</a> v6.3.0</div>




        








        
      </div>
    </footer>

    

    

  </div>

  

<script type="text/javascript">
  if (Object.prototype.toString.call(window.Promise) !== '[object Function]') {
    window.Promise = null;
  }
</script>


























  
  
    <script type="text/javascript" src="/lib/jquery/index.js?v=2.1.3"></script>
  

  
  
    <script type="text/javascript" src="/lib/velocity/velocity.min.js?v=1.2.1"></script>
  

  
  
    <script type="text/javascript" src="/lib/velocity/velocity.ui.min.js?v=1.2.1"></script>
  


  


  <script type="text/javascript" src="/js/src/utils.js?v=6.3.0"></script>

  <script type="text/javascript" src="/js/src/motion.js?v=6.3.0"></script>



  
  

  
  <script type="text/javascript" src="/js/src/scrollspy.js?v=6.3.0"></script>
<script type="text/javascript" src="/js/src/post-details.js?v=6.3.0"></script>



  


  <script type="text/javascript" src="/js/src/bootstrap.js?v=6.3.0"></script>



  



	





  





  








  <script src="//cdn1.lncld.net/static/js/3.0.4/av-min.js"></script>
  
  
  <script src="//unpkg.com/valine/dist/Valine.min.js"></script>
  
  <script type="text/javascript">
    var GUEST = ['nick','mail','link'];
    var guest = 'nick,mail,link';
    guest = guest.split(',').filter(function (item) {
      return GUEST.indexOf(item)>-1;
    });
    new Valine({
        el: '#comments' ,
        verify: false,
        notify: false,
        appId: 'YdGFHBfuDwObik8qwCeRAWgr-gzGzoHsz',
        appKey: 'oFpbJwmMQf98DfFDUlzE5Fai',
        placeholder: 'Just go go',
        avatar:'mm',
        guest_info:guest,
        pageSize:'10' || 10,
    });
  </script>



  





  

  

  

  

  
  

  

  

  

  

  

</body>
</html>
